SPACE 1

home *** CD-ROM | disk | FTP | other *** search

/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / misc~1 / 201 / context / context.doc < prev next >

Wrap

Text File | 1988-06-06 | 23.8 KB | 577 lines

=========================================================================== *************** ConTEXT v2 **************** A Programming Editor (C) Don Milne and MicroPack Ltd 1986 =========================================================================== Here at last (yet again) the long promised version two of my programming editor. I finally decided to call it ConTEXT (as opposed to Context, ConText or CONTEXT). I originally used that name partly because that seems a nice name for an editor, and partly because it was the name I had thought up for a context-sensitive editor that I never got around to writing (I went off the context-sensitive idea before I had written a line). When I released version one of this program I said in the docs that I was reasonably sure that there was no serious bugs in it. Boy was I wrong! The basis of my original confidence was that I was using the program myself every day and had found no bugs, but I had not appreciated just how much some peoples working practices differed from mine - and some of those different but quite valid practices turned up bugs that I had not. My grateful thanks goes to Ron Sprunger who put in a great deal of his time and provided me with two detailed lists of bugs, misfeatures and improvement suggestions. These were invaluable to me in preparing ConTEXT v2. My thanks also to Jim Fox for uploading the code to BIX at a time when I did not myself have the necessary software (well, I had CrossTalk (on a PC) which supports Xmodem, but Xmodem is just too slow and expensive for uploading from the UK). I had hoped to provide multiple editing windows in this version of ConTEXT, but that will take a certain amount of work to achieve, and I simply cannot afford the time at the moment (not unless ConTEXT becomes a paying concern at any rate). So, rather than withhold the program until every last feature is added I have decided to get it out *now* and start getting feedback *now*. Do let me know what you think of my work either on BIX (my BIX-ID is "mpack"), or by phone or mail (see below for the address). ConTEXT is distributed on a shareware basis - it is not public domain. I like the shareware concept because I am a programmer who does not believe in copy protection, or in charging rip-off prices for a piece of code. However I *do* believe that a programmer should be payed a fair price for his work, and I have put a great deal of work into this. If you use this program and feel that it is worth something then I would be grateful if you could send me whatever you think it is worth (I think that around $40 is about right - or 40 pounds if you live in the UK). Remember that the amount of time I devote to this program in future will depend greatly on how much you make it worth my while - I have to eat you know! As an incentive, users who register register will receive a copy of the latest version of the editor, and will be informed when later versions are available, and will be able to get those updates for the price of a disk and the return postage. The Modula-2 program source will also be available to registered users for a further payment of $50 (or 50 pounds in the UK), you can order it when you register if you like. Our address is in the 'About ConTEXT' box in the editor. Payment is by bankers draft, or by cheque drawn on a UK bank made payable to 'MicroPack Ltd'. We can also accept payment by VISA or American Express, if you want to do so then please drop me a line (on BIX, or by phone or mail), giving me the card number, the expiry date, and the name of the card holder. --------------------------------------------------------------------------- ConTEXT's sole reason for existance is that TDI's editor was so bad, I was prepared to write my own rather than use theirs. 1st Word is a good editor in many ways (and still is for real word processing), but as a programming editor just couldn't hack it (I'm spoiled - I can't work without autoindent by default, plus integration with the compiler). Note that if you want to use this editor from the TDI Desktop, you should rename CONTEXT.PRG as EDITOR.PRG (that's what the Desktop looks for when you invoke the editor). ConTEXT can be operated using the standard GEM mouse and menu interface, or entirely from the keyboard. The keyboard commands are totally configurable, and comes ready configured with commands which are almost all WordStar (tm) compatable - users of the Turbo Pascal (tm) editor will also find these commands familiar. ConTEXT also makes use of some of the special purpose keys on the Atari ST keyboard. As a consequence of various tricks being used to speed up Screen IO, ConTEXT does not interact all that well with some Desk Accessories, one unfortunate example being the M2 Options Accessory. This is one bug that has remained from the original version of the editor, mainly because it is not much of a problem - in fact the only accessory I have found which gives problems is TDI's one, so now I just don't use it within ConTEXT. ConTEXT requires an Atari 520 or 1040 ST, Monochrome or Medium Res Color. Don Milne. MicroPack Ltd. ------------------------------------------------------------------------ The Files on the Disk ===================== These are the files which you recieve with ConTEXT:- CONTEXT.PRG - ConTEXT, the program itself. CONTEXT2.RSC - the resource file for ConTEXT, usable in mono or medium res. This must be in the current directory when ConTEXT is run. CCONTEXT.PRG - Configure ConTEXT. Use this program to change the keyboard commands to some you like better. Also used to load the compiler error messages, and the "built-in" macros. CONTEXT.CFG - ConTEXT's configuration file, produced by CCONTEXT. This must be in the current directory when ConTEXT is run. ERRORS.TXT - A list of errors reported by the compiler. This file is required by CCONTEXT. MACROS.TXT - A list of macros to be bound in to the editor as if they were normal, built-in commands. This file is used by CCONTEXT but is not required. CONTEXT.DOC - This file. ------------------------------------------------------------------------ WordStar Command Summary ======================== The following sections describe the default, WordStar/Turbo-compatible command set that I provide as the standard configuration with ConTEXT. If you have reconfigured with your own prefered commands then this will not be of much use to you, but then you ought to know what you did yourself! CURSOR CONTROL -------------- WordStar Cursor movement keys are intended to be mnemonic because of the physical organisation of the keys on a standard keyboard, and not because of the letters on the keys themselves. Unlike the Turbo Pascal editor, all cursor movement commands wrap onto next or previous lines. For example typing cursor-right when the cursor is already at the right of a line causes the cursor to be moved to the beginning of the next line. If your intention was actually to insert a space at the end of the line you should use the space bar instead. Also unlike the Turbo editor is the feature that lines deleted using the "Delete Line" command (^Y or FKey10), are copied into the paste buffer before deletion. The line can be restored by typing the UNDO key. In fact several lines may be deleted at a time, (using consecutive "Delete Line" commands), and all will be restored by typing the UNDO key AS LONG AS YOU DO NOTHING WHICH AFFECTS THE PASTE BUFFER BEFOREHAND. The paste buffer is affected by block operations, and by delete operations. Besides adding a touch of protection against disasters, this feature is often used in preference to a WordStar block command. Where just a few lines are involved this method is usually more convenient. Text removed using the Block Delete command is also copied into the paste buffer and may be restored by typing UNDO. The only major deviation from Turbo is that ConTEXT uses the "^Q-E" sequence to mean "Find Error" (find a compiler-reported error). In WordStar/Turbo, ^Q-E means "move to top-of-page". The opposite command (^Q-X, "move to bottom-of-page"), is also removed to preserve symmetry. Also note that ConTEXT interpretes the "Global" flag in replace operations somewhat differently - In the Turbo editor setting "Global" means "Replace all occurrences of the target", while ConTEXT interpretes it as "Replace all occurrences of the target STARTING FROM THE CURRENT CURSOR POSITION". To achieve the same results as the Turbo example you need to jump to the top of the file before executing the replace. Movement Commands ----------------- Command Description Keystroke(s) ST Alternate Line Up ^E Cursor Up Line Down ^X Cursor Down Character Left ^S Cursor Left ( <-- ) Character Right ^D Cursor Right ( --> ) Word Left ^A Word Right ^F Scroll Up ^W Scroll Down ^Z Page Up ^R '-' key on keypad Page Down ^C '+' key on keypad Left on Text '0' key on keypad Left on Line ^Q-S Right on Line ^Q-D '.' key on keypad Top of File ^Q-R '*' key on keypad End of File ^Q-C 'Enter' key on keypad Start of Block ^Q-B End of Block ^Q-K Jump to Marked Position ^K-J Insert and Delete Commands -------------------------- Command Description Keystroke(s) ST Alternate Insert Mode On/Off ^V Insert Insert Line ^N Delete Line ^Y FKey10 Undelete Lines Undo Delete to End of Line ^Q-Y Delete Character under Cursor ^G Delete Delete Character to Left ^H BackSpace Delete Word ^T^T or ^T-T Insert Tab (size 1) ^I Tab Insert Tab (size 2) ALT-TAB Block Commands -------------- Command Description Keystroke(s) ST Alternate Mark Block Begin ^K-B FKey7 Mark Block End ^K-K FKey8 Mark Single Word ^K-T Hide/Display Block ^K-H Copy Block ^K-C Move Block ^K-V Delete Block ^K-Y Read Block from Disk ^K-R Write Block to Disk ^K-W Print Block ^K-P Macro Commands -------------- Command Description Keystroke(s) ST Alternate Execute Macro FKey2 Read Macro FKey3 Record Macro FKey4 Write Macro FKey5 File Commands ------------- List File on Printer ^K-L Save File and Resume Editing ^K-S Save to Named File ^K-N Save and Edit New File ^K-D Save File and Exit ^K-X Abandon File ^K-Q Misc. Commands -------------- Repeat last Find/Replace ^L Find ^Q-F Replace ^Q-A Find Compile Error ^Q-E Set Marker ^K-M Adjust Indentation ^K-I Toggle Word Case ^T-U Toggle Word Capitalisation ^T-C Toggle Auto-Indent ^Q-I Toggle WP Mode ^Q-W (enables word wrap and paragraph reformat command) Reformat Paragraph ^B Enter a repeat factor <ESC>nn (entered before a command or character causes that command to be repeated nn times or that character to be inserted nn times). Note that ^L repeats the last find, or the last replace, or the last find error. A find error is done automatically by ConTEXT when an error file is detected, so ^L may be used right away in those cases (up until a normal find or replace operation has been carried out). The "Repeat" field in Find/Replace dialog boxes is also an undercover WordStar options field. In other words, as well as being able to enter digits from 0-9 (specifying a repeat factor), it is also possible to enter letters from the set "ABGNQUW" each of which correspond to a particular search option. The meanings of these letters is as follows:- n ---------- A number, repeat the operation n times A ---------- Abort Operation (same as clicking on CANCEL), except that you still need to press return to confirm. B ---------- Search Backwards G ---------- Global, only applies to Replace. Repeat replace operation for all occurrences of the target string searching from the current cursor position. U ---------- Convert target and pattern to uppercase before comparing (ie ignore case differences). W ---------- Whole words only. Patterns match only if the candidate is delimited by non-alphanumeric characters. Q ---------- Set QUERY mode, ie ask user to confirm before completing each replace operation. The "Set Marker" is used in conjunction with the "Jump to Marker" command and allows you to quickly return quickly to any point in a file if you have to leave it for some reason. Notes on Mouse/Menu Operations ============================== The functions provided in the menus are more or less the same as those provided in the WordStar/Turbo Command Set. Additional features are 1. The text cursor may be quickly moved to any position on the screen by pointing with the mouse and clicking once with the left mouse button. 2. Blocks may be marked by pointing with the mouse to the first character of the block, then holding down the left mouse button while the mouse cursor is moved to the last character of the block. A box will be grown around the text to be marked. When the box encloses all of the desired text, the mouse button may be released. The marked block will be highlighted. Obviously, this method may only be used when the entire text is visible on the screen at once, otherwise one of the alternative methods (eg menu or WordStar command or function keys) must be used. Processing of Compile Errors ============================ Errors are handled in the same way as the standard TDI editor. When a file is selected for editing ConTEXT looks for a matching file ending in ".ERM" (or ".ERD" if the file is a definition module). ConTEXT uses information from this file to mark errors in the source file. The marker used looks like this - '@'. Macros and Macro Syntax ======================= The best way to describe the macro syntax is by example, so here is a simple macro:- .macro R REPEAT UNTIL ;$ All macros (in written form that is), start with the header ".macro c" where c can be any single character. This entire header (including the character) is case dependant - ".MACRO" is not acceptable, and 'C' is not the same as 'c' for the identifying character. The macro itself is then a sequence of characters terminated by the character '$'. It is also possible to invoke functions from within a macro by enclosing a "function number" in angle brackets - if we elaborate our example a little:- .macro R REPEAT UNTIL ; <1><6:4><1>$ "<1>" means "Execute function 1" (Function 1 is the Cursor-Up command, a list of function numbers can be found in Appendix A, and is also displayed in the CCONTEXT program. You don't need to know function numbers if you use the "Record Macro" way of creating the macro). The second function looks a little strange bacause it specifies a repeat factor - "<6:4>" means repeat function 4 (cursor right), 6 times. Always remember that the repeat factor is the first number, then a colon, then the function number. It is possible to specify a repeat factor without specifying a function to execute, in which case the repeat factor is reserved for the character following the closing angle bracket, for example the sequence:- <45:>* Will write the '*' character 45 times. Finally, the angle bracket can be used as an escape character to introduce a character that would otherwise have special meaning to the macro syntax checker, for example the sequence:- <$ means "insert the character '$' in the text - do not treat this as the end of the macro". Generally speaking any character may be placed after a left angle bracket to be literally inserted into the text - the following characters can ONLY be inserted in this way:- '<' '$' '|' Note that when using the '<' escape to enter special characters that you do not need to enter a closing bracket, in fact if you do you will find it also inserted into the text!. The last thing you may find useful to know about macro syntax is that you can replace any occurrence of a carriage return with the character '|'. This allows you to write your macros in a more compact form. If we take our example for the last time we can write it thusly:- .macro R|REPEAT||UNTIL ;|<1><6:4><1>$ The file MACROS.TXT contains examples of several macros that you may find useful, including one to strip out hard tabs from a text file, plus several of use to Modula-2 programmers. The macros in this file get bound in to the configuration file and seem to the ConTEXT user to be built in commands of the editor - saves having to re-enter your favorite macros every time! Macros can be created in three ways:- 1. Write your macro in text form into the MACROS.TXT file and use the CCONTEXT program to bind it into the editor. 2. Write your macro in text form then read it with the "Read Macro" command. 3. Record a macro by invoking the "Record Macro" command, do whatever it is once, then invoke the "Record Macro" command again to complete the recording. However you create your macro you need to remember the character you used to identify it, because this is asked for when you invoke the "Execute Macro" command, and when you invoke the "Write Macro" command. The "Write Macro" command can be used to write *any* macro out in text form - regardless of how it was created. The CCONTEXT (Configure ConTEXT) Program ======================================== CCONTEXT should be simple enough to operate (in fact I hope that it is self-explanetory), however this section will summarise its operation. The CCONTEXT program is used to configure the keyboard commands, and also to bind in macros and compiler error messages into the editor. When you run the program the following menu is displayed:- 1. Edit Keyboard Commands 2. Edit Misc Details Q. Quit Option 1 - Edit Keyboard Commands --------------------------------- Option one brings up a secondary menu consisting of a list of the editor commands which you may configure, selectable by function number (the function numbers shown are the same as those recognised by the macro processor). You may then pick a function that you want to configure by typing its function number. You may provide more than one command sequence for any function, but there must be no more than 120 sequences in total (this allows for two sequences for each function, which should be plenty). After you have picked the function that you want to configure, you are given the opportunity to add, or remove a function. To add a function just press 'a', then type the two characters that make up the command. If the command is only one character then type <CR> for the second character. Option 2 - Edit Misc Details ---------------------------- This option allows you to configure such details as:- a) The background color (black or white). b) The tab sizes (two tab commands are provided). c) The initial settings of various flags, ie Insert Mode, Auto-Indent On/Off, WP Mode. Q - Quit -------- Quits the CCONTEXT program and causes it to write out the new configuration file. For this the ERRORS.TXT file must be in the current directory, and you should have the MACROS.TXT file also in the current directory if you want the macros therein to be bound into the configuration. MACROS.TXT is simply a list of the macros you want bound in, specified using the same macro syntax used by the Macro Processor which is part of the ConTEXT editor. The only "extras" in MACROS.TXT is that you may add comments before and after macros (but not within macros!). Any line starting with a ';' in the first column is treated as a comment line and is ignored. You may also have blank lines in your macro file - before and after a macro blank lines have no significance, within a macro they certainly do! See the supplied MACROS.TXT file for an actual example. APPENDIX A - Macro Processor Function Numbers --------------------------------------------- Function Function Number Description -------- ----------- 1 Cursor Up 2 Cursor Down 3 Cursor Left 4 Cursor Right 5 Backspace 6 Page Up 7 Page Down 8 Word Move Left 9 Word Move Right 10 Scroll Up 11 Scroll Down 12 Start Of File 13 End Of File 14 Delete Char 15 Delete Line 16 Delete to EOL 17 Delete Word 18 Undelete Lines 19 Insert Line 20 Left on Line 21 Left on Text 22 Right on Text 23 Mark Start of Block 24 Mark End of Block 25 Mark Single Word 26 Find Start of Block 27 Find End of Block 28 Hide/Display Block 29 Copy Block 30 Move Block 31 Delete Block 32 Read Block 33 Write Block 34 Print Block 35 Find 36 Find and Replace 37 Find Compile Error 38 Find/Replace again 39 Set Marker 40 Jump to Marker 41 Print File 42 Save File 43 Save File As... 44 Save & Edit new File 45 Save and Exit 46 Abandon Changes 47 Adjust Indent 48 Switch Window 49 Execute Macro 50 Read Macro 51 Record Macro 52 Write Macro 53 Tab 54 Tab 2 55 Toggle Word Case 56 Toggle Capitalisation 57 Toggle Insert Mode 58 Toggle Auto-Indent 59 Toggle WP Mode 60 Reformat Paragraph